home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.036 < prev    next >
Encoding:
Text File  |  1989-09-03  |  14.0 KB  |  354 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIGS
  7. #36:    Port Driver Specifications
  8.  
  9. Revised by:    Matt Deatherage & Suki Lee                      September 1989
  10. Written by:    Dan Hitchens                                          May 1988
  11.  
  12. This Technical Note describes how to write your own drivers for Apple IIGS 
  13. ports.
  14. Changed since January 1989:  Added description of new port driver 
  15. structure.
  16. _____________________________________________________________________________
  17.  
  18.  
  19. Introduction
  20.  
  21. A port driver handles certain hardware-specific duties for the Print Manager, 
  22. such as initializing firmware and handling low-level hardware handshaking 
  23. protocols, if any are implemented.  The port driver structure, like the 
  24. printer driver structure, insulates the Print Manager from low-level details 
  25. of printers and interface cards (or ports) so that the same calls work across 
  26. various hardware configurations, provided drivers are installed on the boot 
  27. disk.
  28.  
  29. Note that a port driver could also easily be called a card driver; the term 
  30. port is used because the first ones written were for the internal ports of the 
  31. Apple IIGS.  A port driver could interface any printer (for which there is a 
  32. printer driver) with any kind of port or peripheral card that can handle it.  
  33. A familiar example would be a parallel printer interface card--a port driver 
  34. for a parallel card would enable the Print Manager to print graphics to any 
  35. parallel printer connected to it (provided, again, there was a printer driver 
  36. for the particular printer installed).
  37.  
  38. In general, you need a port driver for each port or interface card through 
  39. which you intend to print, and a printer driver for each printer to which you 
  40. intend to print.  On System Disk 4.0, Apple provides port driver files for the 
  41. printer port (PRINTER), the modem port (MODEM), a port connected to the 
  42. AppleTalk network (APPLETALK), and a parallel printer interface card 
  43. (PARALLEL.CARD).  Apple also provides printer drivers for the ImageWriter and 
  44. ImageWriter II (IMAGEWRITER), the ImageWriter LQ (IMAGEWRITER.LQ), the 
  45. LaserWriter family.(LASERWRITER), and an Epson (EPSON).  With this 
  46. configuration, you can print to any of the printer types above through any of 
  47. the ports, cards, or over AppleTalk.  Other printer drivers and port drivers 
  48. would extend the user's selection of available configurations.
  49.  
  50.  
  51. What's in a Port Driver
  52.  
  53. File Structure
  54.  
  55. Users can install new port drivers into the system by copying a port driver 
  56. file into a subdirectory called DRIVERS within the SYSTEM subdirectory or by 
  57. running the Installer if the driver is supplied with a script to install it.  
  58. The port driver file must be of type $BB.  There are two kinds of port 
  59. drivers:  local drivers, intended to drive a printer connected locally, and 
  60. network drivers, which handle printers connected over an AppleTalk network.  
  61. Local drivers have an auxiliary type of $0002, and AppleTalk drivers (there 
  62. should be only one) have an auxiliary type of $0003.
  63.  
  64. Port Driver Calls
  65.  
  66. A port driver must support the following calls:
  67.  
  68.     PrDevPrChanged          $1913
  69.     PrDevStartup            $1A13
  70.     PrDevShutDown           $1B13
  71.     PrDevOpen               $1C13
  72.     PrDevRead               $1D13
  73.     PrDevWrite              $1E13
  74.     PrDevClose              $1F13
  75.     PrDevStatus             $2013
  76.     PrDevAsyncRead          $2113    (alias PrDevInitBack)
  77.     PrDevWriteBackground    $2213    (alias PrDevFillBack)
  78.     PrPortVer               $2413
  79.     PrDevIsItSafe           $3013
  80.  
  81. Note that a network port driver has much more work to do than a regular 
  82. (local) port or card driver.  A local driver only has to worry about one 
  83. printer, whereas a network port driver may find that there is not even a 
  84. printer available on a running network.  The information on network drivers is 
  85. provided mostly for informational purposes; you should never find it necessary 
  86. to write your own AppleTalk port driver.
  87.  
  88. Entering and Exiting a Port Driver 
  89.  
  90. Entering and exiting is the same as described for the printer driver calls in 
  91. Apple IIGS Technical Note #35, Printer Driver Specifications.  The new driver 
  92. structure described there applies as well.  As of this writing, there are no 
  93. optional calls a port driver may support.  The documented list must be 
  94. supported in its entirety.
  95.  
  96.  
  97. PrDevPrChanged           $1913
  98.  
  99. Description:
  100.     The Print Manager makes this call every time the user accepts this port 
  101.     driver in the Choose Printer dialog.
  102.  
  103. Input:                   LONG        printer name pointer
  104.  
  105. Direct Connect:
  106.   o  Makes sure that this port has been set up correctly in the Control Panel 
  107.      (parity, baud rate, etc.), and puts up an alert for the user if it has not 
  108.      been.  Remember that if you change settings, even at the user's request, 
  109.      you should change the Battery RAM parameters as well, so the setting 
  110.      changes will be reflected when the user enters the Control Panel.
  111.  
  112. Network:
  113.   o  Copies the printer name to local storage for use in the NBPLookup function 
  114.      of the AppleTalk PAPopen and PAPstatus calls, usually by placing it in the 
  115.      AppleTalk parameter block.  This function is similar to that performed by 
  116.      PrStartUp, except that PrDevPrChanged is called whenever the printer is 
  117.      changed by the user with the Choose Printer dialog.
  118.  
  119.  
  120. PrDevStartUp             $1A13
  121.  
  122. Description:
  123.     This call is not required to do anything.  However, if your driver needs to 
  124.     initialize itself by allocating memory or other setup tasks, this is the 
  125.     place to do it.  Network drivers should copy the printer name to a local 
  126.     storage area for later use.
  127.  
  128. Input:                   LONG        printer name pointer
  129.                          LONG        zone name pointer
  130.  
  131. Direct Connect:
  132.   o  Required to do nothing.  This is a good place to do your own set-up tasks, 
  133.      if you have any.
  134.  
  135. Network:
  136.   o  Copies the printer name and the zone name to local storage for use in the 
  137.      NBPLookup function of the AppleTalk PAPopen and PAPstatus calls, usually by 
  138.      placing it in the AppleTalk parameter block.
  139.  
  140.  
  141. PrDevShutDown            $1B13
  142.  
  143. Description:
  144.     This call, like PrDevStartUp, is not required to do anything.  However, if 
  145.     your driver performs other tasks when it starts, from the normal 
  146.     (allocating memory) to the obscure (installing heartbeat tasks), it should 
  147.     undo them here.  If you allocate anything when you start, you should 
  148.     deallocate it when you shutdown.  Note that this call may be made without a 
  149.     balancing PrDevStartUp, so be prepared for this instance.  For example, do 
  150.     not try to blindly deallocate a handle that your PrDevStartUp routine 
  151.     allocates and stores in local storage; if you have not called PrDevStartUp, 
  152.     there is no telling what will be in your local storage area.
  153.  
  154. Input:                   none
  155.  
  156.  
  157. PrDevOpen                $1C13
  158.  
  159. Description:
  160.     This call basically prepares the firmware for printing.  It must initialize 
  161.     the firmware for both input and output.  Input is required so the connected 
  162.     printer may be polled for its status.
  163.  
  164.     A network driver has considerably more work to do, including the 
  165.     possibility of asynchronous communications.  Details are provided below.
  166.  
  167. Input:                   LONG        completion routine pointer 
  168.                          LONG        reserved long
  169.  
  170. Direct Connect:
  171.   o  Initializes the firmware for input and output, preparing for reading from 
  172.      or writing to the printer.
  173.   o  If the completion pointer is NIL, then RTL.  If it is not NIL, then perform 
  174.      a JSL to the completion routine.
  175.  
  176. Network:
  177.   o  Initializes the End-Of-Write parameter in the AppleTalk PAPWrite parameter 
  178.      block to zero.  Never call AppleTalk INIT to initialize the firmware.
  179.   o  If the completion pointer is NIL, then prepares for synchronous 
  180.      communications.  If it is not NIL, prepares for asynchronous printing.
  181.   o  Calls AppleTalk PAPopen to make connection, returning an error if one is 
  182.      returned to you.
  183.   o  Stores the AppleTalk Session number in the PAPRead, PAPWrite and PAPClose 
  184.      parameter blocks.
  185.   o  Executes an RTL if there is no completion routine (pointer is NIL), 
  186.      otherwise perform a JSL to the completion routine.
  187.  
  188.  
  189. PrDevRead                $1D13
  190.  
  191. Description:
  192.     This call reads input from the printer.
  193.  
  194. Input:                   WORD        space for result
  195.                          LONG        buffer pointer
  196.                          WORD        number of bytes to transfer
  197.  
  198. Output:                  WORD        number of bytes transferred 
  199.  
  200. Direct Connect:
  201.   o  Reads a specified number of bytes from the printer into the buffer.
  202.  
  203. Network:
  204.   o  Calls AppleTalk PAPRead to read synchronously.  Since there is no 
  205.      completion pointer, reading from a network device must always be done 
  206.      synchronously.  To read asynchronously, use PrDevAsyncRead.
  207.  
  208.  
  209. PrDevWrite              $1E13
  210.  
  211. Description:
  212.     Writes the data in the buffer to the printer and calls the completion 
  213.     routine.
  214.  
  215. Input:                   LONG    write completion pointer
  216.                          LONG    buffer pointer
  217.                          WORD    buffer length
  218.  
  219. Direct Connect:
  220.   o  Writes the contents of the buffer to the printer.
  221.   o  If the completion pointer is NIL, then RTL.  If it is not, then perform a 
  222.      JSL to the completion routine.
  223.  
  224. Network:
  225.   o  If the completion pointer is NIL, then writing will occur synchronously.  
  226.      Otherwise, writing will occur asynchronously.
  227.   o  Calls AppleTalk PAPWrite to transfer the contents of the buffer.
  228.   o  If the completion pointer is NIL, then RTL to the caller.  Otherwise, 
  229.      perform a JSL to the completion routine first, with the error code in the 
  230.      accumulator.
  231.  
  232.  
  233. PrDevClose               $1F13
  234.  
  235. Description:
  236.     This call is not required to do anything.  However, if you allocate any 
  237.     system resources with PrDevOpen, you should deallocate them at this time.  
  238.     As with start and shutdown, note that PrDevClose could be called without a 
  239.     balancing PrDevOpen (the reverse is not true), and you must be prepared for 
  240.     this if you try to deallocate resources which were never allocated.
  241.  
  242. Input:                   none
  243.  
  244. Direct Connect:
  245.   o  No required function.
  246.  
  247. Network:
  248.   o  Sets End-Of-Write parameter in AppleTalk PAPWrite parameter block to one.
  249.   o  Calls PAPWrite with no data.
  250.   o  Calls PAPClose.
  251.  
  252.  
  253. PrDevStatus              $2013
  254.  
  255. Description:
  256.     This call performs differently for direct connect and network drivers.  For 
  257.     direct connect drivers, it currently has no required function, although it 
  258.     may return the status of the port in the future.  For network drivers, it 
  259.     calls an AppleTalk status routine, which returns a status string in the 
  260.     buffer (normally a string like "Status:  The print server is spooling your 
  261.     document").
  262.  
  263. Input:                   LONG        status buffer pointer
  264.  
  265. Direct Connect:
  266.   o  Does nothing.
  267.  
  268. Network:
  269.   o  Calls AppleTalk PAPStatus.
  270.  
  271.  
  272. PrDevAsyncRead          $2113
  273.  
  274. Description:
  275.     Since PrDevRead cannot read asynchronously, this call is provided for that 
  276.     task.  Note that this does nothing for direct connect drivers, and if the 
  277.     completion pointer is NIL, it behaves for network drivers exactly as 
  278.     PrDevRead does.
  279.  
  280. Input:                   WORD        space for result
  281.                          LONG        completion pointer
  282.                          WORD        buffer length
  283.                          LONG        buffer pointer
  284.  
  285. Output:                  WORD        number of bytes transferred
  286.  
  287. Direct Connect:
  288.   o  Does nothing.
  289.  
  290. Network:
  291.   o  If the completion pointer is NIL, then performs exactly as PrDevRead.
  292.   o  Calls AppleTalk PAPRead; the actual length read is passed back in the 
  293.      PAPRead parameter block.
  294.   o  Perform a JSL to the completion routine, which returns the length read in 
  295.      the X register and an EOF flag in the Y register.  As usual, the 
  296.      accumulator contains the error code and the carry is set if an error 
  297.      occurs.
  298.   o  In the case of a synchronous call, it performs a JSL to the completion 
  299.      routine, which pushes the length read onto the stack.
  300.  
  301.  
  302. PrDevWriteBackground    $2213
  303.  
  304. Description:
  305.     This routine is not implemented at this time.
  306.  
  307. Input:                   LONG        completion procedure pointer
  308.                          WORD        buffer length
  309.                          LONG        buffer pointer
  310.  
  311.  
  312. PrPortVer               $2413
  313.  
  314. Description:
  315.     Returns the version number of the currently installed port driver.
  316.  
  317. Input:                   WORD        space for result
  318.  
  319. Output:                  WORD        Port driver's version number
  320.  
  321. Direct Connect and Network:
  322.   o  Gets the internal version number of the port driver and returns it on the 
  323.      stack.
  324.  
  325. Note:  The internal version number is stored as a major byte and a
  326.        minor byte (i.e., $0103 represents version 1.3)
  327.  
  328.  
  329. PrDevIsItSafe            $3013
  330.  
  331. Description:
  332.     This call checks to see if the port or card which your driver controls is 
  333.     enabled.  It should check at least the corresponding bit of $E0C02D, and 
  334.     checking the Battery RAM settings wouldn't hurt any either.
  335.  
  336. Input:                   WORD        space for result
  337.  
  338. Output:                  WORD        Boolean indicating if port is 
  339.                                      enabled 
  340.  
  341. Direct Connect and Network:
  342.   o  Checks the system to see if the hardware and/or firmware for the card or 
  343.      port this driver controls is enabled, and returns TRUE if it is safe to 
  344.      proceed and FALSE if not.  Note that for a port driver that controls an 
  345.      interface card, this call should return FALSE if the card is disabled and 
  346.      the port is enabled, while for a port driver which controls an Apple IIGS 
  347.      internal port, the returned value should be TRUE if the port is enabled and 
  348.      FALSE if not.
  349.  
  350.  
  351. Further Reference
  352. _____________________________________________________________________________
  353.   o  Apple IIGS Toolbox Reference, Volumes 1 & 2
  354.   o  Apple IIGS Technical Note #35, Printer Driver Specifications